EnRoute Developer Tech Note 1                              ERDTN-1

Subject:    i-net Routing

Revision:   1.0
Date:       Sept. 20, 1996
Author:     Les R. Titze
History:    1.0 - LRT

From a Newton application developer's perspective, the EnRoute internet transport can be treated as a standard mail transport as described by the Newton Programmer's Guide in chapter 2 of the Communications volume.

It provides full routing services for text data (as do most Newton mail transports) and native Newton frame data, allowing users to mail either type of information from the application via the internet.

In addition EnRoute is able to route raw binary data using the data type "routeBinary". This allows Newton applications to share data with applications which use traditional files as their medium of exchange.

Descriptions of these three forms of routing follow.  For further information about the standard 'text and 'frames data types, please refer to the Communications volume of the Newton Programmer's Guide.

TEXT
----
Text data is transmitted as standard email body text and will be received as such by both desktop and Newton mail client software.

Some applications may prefer to transmit data in this format by creating a textual representation of their internal data which can be read or manipulated manually by the receiver of the mail message.


FRAMES
------
For applications which can send data in a format intended for use on another Newton, the 'frames data type is preferred.

Frame data is sent over the internet as part of a standard MIME email message. The frame data portion is a uuencoded MIME part formatted as illustrated here:

  ========--UniqueBoundaryID--========
  Content-Type: application/octet-stream; name="Msg subj text str"
   ; x-mac-type="96657774"
   ; x-mac-creator="726FB574"
  Content-Transfer-Encoding: x-uuencode
  
  begin 644 MSGSUBJT.NWT
  ...uuencoded data...
  end

Such frame data is treated by most desktop email clients as data to be saved to a file. On the Macintosh, most clients will save the file as a file of type 'ewt' with a creator of type 'rot'.  The file type and creator are not required for transmission of such a file back to a Newton but are provided so that a Macintosh Finder icon can be associated with the file.

When this data is received by a Newton via the EnRoute internet transport, it is recognized by its content as frame data and is converted back to the same form that it had when created by the original Newton application.  Further information regarding the format of EnRoute frames files is available on request from Netstrategy Software Inc.

Note: When receiving enclosures, EnRoute is able to accept MIME base64 encoded as well as uuencoded content and can also recognize and decode AppleFile MIME parts.


BINARY
------
The standard Newton routing formats do not provide a method for an application to convert data to and from desktop data files.  To address this need, the EnRoute internet transport provides its own routing data type which third party developers are free to use.

By providing a routing format which includes the data type 'routeBinary, any Newton application can send and receive desktop file data.

As an example, a graphics application which was able to convert its data to JPEG format could transmit its images to the desktop where they would be available as standard JPEG files.  If it was also able to recognize and interpret JPEG data files, it could accept such files when they were received by EnRoute and display them on the Newton.

A simple NewtApp based sample project is available from Netstrategy Software Inc which illustrates how to take advantage of this feature of the EnRoute internet transport.


Using routeBinary to send
-------------------------
An application indicates that it wishes to route data of a particular data type by providing a routing format with a slot named 'dataTypes containing an array containing the data formats which theis format is responsible for.  The routing format should also have a SetupItem function which will be called by the routing system to allow the application to create the data which will be transmitted.

A routeBinary application would have a routing format frame defined as follows:

  {
  _proto:       protoFrameFormat,
  title:        "Desktop File",
  symbol:       '|routeBinFile:BinSample:LRT|,
  dataTypes:    [ 'routeBinary ],
  version:      1,
  SetupItem:    func ( item,targetFrame )
    begin
    // this example is just a cheap trick to put
    // some junk into the body frame's data slot

    local it := targetFrame.target;

    local sampleText := "MyTpMyAp\nExported data\n\n";

    sampleText := sampleText
      & "Title:\t"
      & it.title
      & $\n;

    sampleText := sampleText
      & "Text:\t"
      & it.text
      & $\n;

    local binObj := MakeBinary ( StrLen(sampleText)+1, 'binary );
    StuffCString ( binObj, 0, sampleText );
    SetLength ( binObj, StrLen ( sampleText ) );

    // the following will be similar for all applications
    item.body :=
      {
      class:    'routeBinary,
      data:     binObj,
      fName:    "EXPORT.MYT",
      fType:    "MyTp",
      fCreator: "MyAp",
      };

    // Applications should only make changes to item.body
    // and item.text as these are defined by Apple as the
    // only slots in mail items which are guaranteed to be
    // transmitted by mail transports

    item;
    end,
  }


The format of the item.body slot illustrated above is very important and is the key to successful use of the routeBinary feature of EnRoute.

Slot descriptions for the routeBinary item.body frame

class       Must be 'routeBinary

data        binary object with the data content of the file to be
            transmitted. All of the bytes from this object will appear
            in the resultant data file.

fName       string containing the name of the data file

fType       optional 4 character string for the Macintosh file type

fCreator 	optional 4 character string for the Macintosh file creator


The body.data binary object is sent over the internet as part of a standard MIME email message. The frame data portion is a uuencoded MIME part formatted as illustrated here:

  ========--UniqueBoundaryID--========
  Content-Type: application/octet-stream; name=    <fName>
   ; x-mac-type=     <fType>
   ; x-mac-creator=  <fCreator>
  Content-Transfer-Encoding: x-uuencode
  
  begin 644 <fName>
  ... uuencoded body.data ...
  end



Using routeBinary to receive
----------------------------
To register to receive data from the EnRoute internet transport, an application must include the following in its install and remove scripts:

  InstallScript := func(partFrame)
    begin
    RegAppClasses ( kAppSymbol, [ 'routeBinary ] );
    // ... whatever ...
    end;

  RemoveScript := func(partFrame)
    begin
    UnregAppClasses ( kAppSymbol );
    // ... whatever ...
    end;

Applications registered in this way must also provide a function named "AcceptRoutedBinary" for the inet transport to call when it has binary data which it cannot recognize. The transport calls this function as:

  GetRoot().(appSym):?AcceptRoutedBinary ( mimePart );

AcceptRoutedBinary is passed a single parameter which is a frame representing the information extracted from the MIME enclosure.  AcceptRoutedBinary should examine this frame to determine whether the data belongs to the application, and return TRUE if it recognises it or NIL if it doesn't.

The relevent slots in the mimePart frame are:

  header     - the complete MIME header for this part

  data       - a binary object containing the data from the file

  fName      - the name of the original file

  fType      - the Macintosh file type (if provided)

  fCreator   - the Macintosh file creator (if provided)

If the application wishes to accept the frame it should set the frame's 'kind slot to 'enrouteFrame and set the frame's 'data slot to a frame containing the application's symbol and a body slot filled from the data of the MIME enclosure.  This will ensure that the message will appear in the In Box in a form whereby it can be put away to the application.

An oversimplified example of the AcceptRoutedBinary function follows:


AcceptRoutedBinary: func ( mimePart )
  begin
  local theBinFileData := mimePart.data;

  if TRUE   // might test for something unique in "mimePart.data"
    or (
       mimePart.fType
     and
       StrEqual ( mimePart.fType,    "MyTp" )
     and
       mimePart.fCreator
     and
       StrEqual ( mimePart.fCreator, "MyAp" )   )
    or
      EndsWith ( mimePart.fName, ".MYT" ) then
    begin
    mimePart.kind := 'enrouteFrame;  // required by EnRoute

    mimePart.data :=
      {
      appSymbol:  kAppSymbol,       // required for routing
      body:
        {
        class:    kDataSymbol,      // required for routing
        title:    "Imported Data",
        fName:    mimePart.fName,
        fType:    mimePart.fType,
        fCreator:  mimePart.fCreator,
        importData: theBinFileData,
        timestamp:  Time();
        },
      };

    true;
    end;
  else
    nil;
  end
